<?xml version="1.0" encoding="utf-8"?>
<OAuthUtility>
  <OAuthUtility>
    <summary>A utility for handling authorization and request signatures for the OAuth protocol.</summary>
    <remarks>
      <para>Before you begin, you will need to register your application with Twitter.</para>
      <para>
        To authenticate a user, there are 3 steps you will take:<br/>
        1) Obtain a Request Token<br/>
        2) Authentication<br/>
        3) Obtain an Access Token
      </para>
    </remarks>
    <example>
      First, you must obtain a request token from the API.
      <code lang="cs">
        string consumerKey = "XXX";
        string consumerSecret = "XXX";
        string callbackUrl = "http://example.com/callback.aspx";

        // Obtain a request token
        OAuthTokenResponse requestToken = OAuthUtility.GetRequestToken(consumerKey, consumerSecret, callbackUrl);

        // Direct or instruct the user to the following address:
        Uri authorizationUri = OAuthUtility.BuildAuthorizationUri(requestToken.Token);
      </code>
      <code lang="vb">
        Dim consumerKey As String = "XXX"
        Dim consumerSecret As String = "XXX"
        Dim callbackUrl As String = "http://example.com/callback.aspx"

        '-- Obtain a request token
        Dim requestToken As OAuthTokenResponse = OAuthUtility.GetRequestToken(consumerKey, consumerSecret, callbackUrl)

        '-- Direct or instruct the user to the following address:
        Dim authorizationUri As Uri = OAuthUtility.BuildAuthorizationUri(requestToken.Token)
      </code>
      
      After the user has returned, you must obtain or reuse the request token and obtain the verifier value. For web applications, both values will be provided on the querystring to the callback url as oauth_token and oauth_verifier, respectively. For desktop and mobile applications, the verifier will be a numeric PIN supplied to the user.
      
      <code lang="cs">
        string consumerKey = "XXX";
        string consumerSecret = "XXX";
        string requestToken = "XXX";
        string verifier = "XXX";

        // Obtain the access token for this user.
        OAuthTokenResponse accessToken = OAuthUtility.GetAccessToken(consumerKey, consumerSecret, requestToken, verifier);
        
        // TODO: Save the access token to a database, session, xml file, or whereever my user data is stored.
      </code>
      <code lang="vb">
        Dim consumerKey As String = "XXX"
        Dim consumerSecret As String = "XXX"
        Dim requestToken As String = "XXX"
        Dim verifier As String = "XXX"

        '-- Obtain the access token for this user.
        Dim accessToken As OAuthTokenResponse = OAuthUtility.GetAccessToken(consumerKey, consumerSecret, requestToken, verifier)

        '-- TODO: Save the access token to a database, session, xml file, or whereever my user data is stored.
      </code>
    </example>
    <seealso cref="Twitterizer.OAuthTokenResponse" />
    <seealso cref="Twitterizer.OAuthUtility.GetRequestToken(string,string,string)" />
    <seealso cref="Twitterizer.OAuthUtility.GetAccessToken(string,string,string,string)" />
    <seealso cref="Twitterizer.OAuthUtility.BuildAuthorizationUri(string)" />
  </OAuthUtility>
</OAuthUtility>